home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / rascal.arc / UTILITY.DOC < prev   
Text File  |  1980-01-01  |  14KB  |  421 lines
  1.  
  2.  
  3.  
  4.  
  5.                                   November 1983
  6.  
  7.         This  document  tells  how  to  use  the Rascal program debugger,
  8.         lister, and library routines. These utilities make writing Rascal
  9.         programs  faster and easier. This manual assumes you are familiar
  10.         with MS DOS and Microsoft BASIC.
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.                          RASCAL UTILITIES USER'S MANUAL                         RASCAL UTILITIES USER'S MANUAL
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.                              Manual version:   1.00
  32.  
  33.                              Software version: 1.05
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.                                    Marty Franz
  50.  
  51.                      525 W. Walnut St., Kalamazoo, MI 49007
  52.  
  53.                                  (616) 344-1821
  54.  
  55.  
  56.  
  57.                (C) Copyright 1983 Marty Franz - All rights reserved
  58.  
  59.  
  60.  
  61.         111483105         Rascal Utilities User's Manual
  62.  
  63.  
  64.  
  65.         INTRODUCTION        INTRODUCTION
  66.  
  67.             Rascal is a complete BASIC programming system for the IBM
  68.         Personal Computer.  It features a text editor for entering and
  69.         changing Rascal statements, and a preprocessor for converting
  70.         Rascal programs into BASIC programs that can be executed on the
  71.         PC.  The preprocessor and editor User's Manuals describe these
  72.         programs in detail.  This manual concerns itself with several
  73.         additional programs that can make writing and debugging Rascal
  74.         programs easier:
  75.  
  76.             - LLIST.EXE, a program to list your Rascal source files on a
  77.               printer with your choice of several formatting options,
  78.  
  79.             - DEBUG.INC, a debugger module that lets you debug your
  80.               Rascal programs at the procedure level, and
  81.  
  82.             - the files SCREEN.INC and INPUT.INC, two library files
  83.               containing procedures that can be included into your Rascal
  84.               programs to make your programming easier.
  85.  
  86.  
  87.         PROGRAM REQUIREMENTS        PROGRAM REQUIREMENTS
  88.  
  89.             To successfully use these utility programs, your need an IBM
  90.         PC or XT with:
  91.  
  92.             - at least 64KB of memory,
  93.  
  94.             - at least one single-sided diskette drive,
  95.  
  96.             - a color or monochrome adapter, and a monitor capable of
  97.               displaying 80-character lines,
  98.  
  99.             - MS DOS version 1.1 or 2.0, and
  100.  
  101.             - the files BASICA.COM or BASIC.COM.
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.                                                                          Page 2        111483105         Rascal Utilities User's Manual
  122.  
  123.  
  124.  
  125.         THE PROGRAM DEBUGGER        THE PROGRAM DEBUGGER
  126.  
  127.               The Rascal program debugger is used during development to
  128.         trace Rascal program execution at the procedure level. (For more
  129.         information about "procedures" and the rest of the Rascal
  130.         language, please consult the Rascal User's Manual.)  By including
  131.         the file DEBUG.INC in your program during preprocessing, and
  132.         using the DEBUG and NODEBUG statements, you can perform these
  133.         helpful functions when you are testing your program from within
  134.         BASIC:
  135.  
  136.             - you can see the execution of each procedure on the screen
  137.               as it is called by a DO or GOSUB statement,
  138.  
  139.             - you can set a trap in your program to stop when a certain
  140.               procedure is reached, (this is called a "breakpoint")
  141.  
  142.             - you can stop your program, exit into BASIC, print the
  143.               values of your variables, then resume execution again, and
  144.  
  145.             - you can dump the "stack" of procedures called whenever you
  146.               stop the program's execution.
  147.  
  148.  
  149.         USING THE DEBUGGER        USING THE DEBUGGER
  150.  
  151.             To use the program debugger, you need to include the file
  152.         DEBUG.INC into your Rascal source program.  Then, you must select
  153.         the individual procedures to be debugged by using the DEBUG and
  154.         NODEBUG Rascal statements.  Here's an example:
  155.  
  156.  
  157.                  INCLUDE DEBUG.INC   'Include the debugger procedures.
  158.  
  159.                  DEBUG               'Turn on debugging.
  160.  
  161.                  PROCEDURE MAIN      'First procedure to be debugged.
  162.                      .
  163.                      .
  164.                  ENDPROC
  165.  
  166.                  PROCEDURE ...
  167.                      .               'More procedures to be debugged are
  168.                      .                here.
  169.                  ENDPROC
  170.  
  171.                  NODEBUG            'Turn off debugging.
  172.  
  173.                  INCLUDE SCREEN.INC  'Procedures here will not be
  174.                                       debugged.
  175.  
  176.  
  177.         The statements DEBUG and NODEBUG work just like a switch.  When
  178.         DEBUG is encountered, all the procedures following it will have
  179.         calls to debugger routines generated after their first and last
  180.  
  181.                                                                          Page 3        111483105         Rascal Utilities User's Manual
  182.  
  183.  
  184.         statements.  When NODEBUG is reached, this generation is turned
  185.         off.  Both DEBUG and NODEBUG must appear in a source file outside
  186.         a procedure.  When you run your program from BASIC, these extra
  187.         calls help the debugger determine where in execution is in the
  188.         program.
  189.  
  190.  
  191.         DEBUGGING IN BASIC        DEBUGGING IN BASIC
  192.  
  193.             After your program has been preprocessed with debugger
  194.         statements in it, it can be run from BASIC.  The debugger will
  195.         get control before procedure MAIN does, and will display a list
  196.         of available commands and prompt you for one with "debug:"
  197.         displayed on line 25 of the screen.  The commands you can use in
  198.         the debugger are:
  199.  
  200.                  X    to exit to BASIC with a STOP statement.  This
  201.                       allows you to print key variables in your program
  202.                       and list parts of your code.  The BASIC CONT
  203.                       command can be used to continue execution.
  204.  
  205.                  B    to have the debugger prompt you for a breakpoint.
  206.                       Enter the name of the procedure where you want the
  207.                       program to stop next.  If you don't want to stop at
  208.                       any procedures during execution, just press enter.
  209.  
  210.                  D    to display the names of the procedures currently
  211.                       active, along with their appropriate line numbers.
  212.                       This will be shown  enclosed by a frame in the
  213.                       upper right corner of your screen.  The topmost
  214.                       procedure in the list will be the one currently
  215.                       being executed, with the one below it being the one
  216.                       that called it, etc.  This can be used to help you
  217.                       trace the location of bugs in the program.
  218.  
  219.                  G    to resume execution of the program.
  220.  
  221.             As your program is running, the procedures being executed are
  222.         displayed on line 25 of the screen along with the line number
  223.         they start on.  You can stop execution of the program at any time
  224.         by pressing F10.  This will enter the debugger at the next
  225.         procedure encountered.
  226.  
  227.             Besides stopping at a breakpoint or by F10 on the keyboard,
  228.         the debugger is entered whenever a BASIC error is encountered.
  229.         The error message and line number will be displayed on line 25 of
  230.         the screen.  A line number of 65535 means the error happened in
  231.         direct mode.
  232.  
  233.             The debugger is in Rascal source code and can be changed for
  234.         special needs.  You might want to do this if you are developing
  235.         programs that do a lot of color or graphics, since the debugger
  236.         assumes a text screen with 25 lines of 80 characters. All of the
  237.         debugger's variable definitions are contained in the procedure
  238.         DEBUG.SETUP, which is called before MAIN is when your program is
  239.         started.
  240.  
  241.                                                                          Page 4        111483105         Rascal Utilities User's Manual
  242.  
  243.  
  244.  
  245.         THE LLIST PROGRAM        THE LLIST PROGRAM
  246.  
  247.             The file LLIST.EXE on your Rascal program disk is a
  248.         general-purpose print utility.  With it, you can print your
  249.         Rascal source files, selecting any of several formatting
  250.         options.
  251.  
  252.             LLIST's syntax is similar to other MS DOS commands.  You must
  253.         supply it the name of the file you want to list, and additional
  254.         information through program "switches" to select any extra
  255.         formatting options.  LLIST's format is:
  256.  
  257.                  A>LLIST d:filename.ext {/n /p /s /ln /wn /tn}
  258.  
  259.         Only the "d:filename.ext" is required.  If you don't supply it,
  260.         LLIST will display a brief summary of its operation and options
  261.         and prompt you for it.  The switches in squiggly braces control
  262.         these options:
  263.  
  264.                  /n    omits page headings from the listing. Normally,
  265.                        your listing will have the filename, date, time,
  266.                        and page number at the top of each page.  The /n
  267.                        switch overrides this.
  268.  
  269.                  /p    is used when you are printing on single-sheet
  270.                        paper.  This will pause the program between pages
  271.                        so you can change sheets.  Press the "enter" key
  272.                        to continue with the next page.
  273.  
  274.                  /s    includes line numbers in the listing.  This switch
  275.                        is especially useful when you are debugging Rascal
  276.                        programs and you need to match the line numbers of
  277.                        the preprocessor's error messages to the source
  278.                        statement.
  279.  
  280.                  /ln   sets the length of a page to n lines.  This is
  281.                        useful when printing on short forms or in
  282.                        compressed format.  Normally, this option is set
  283.                        to 60 lines/page.
  284.  
  285.                  /tn   sets tab stops every n columns.  Normally, you
  286.                        don't need to use this with Rascal source files,
  287.                        since it is set by default to 4 columns.  You
  288.                        might need to change this option for other
  289.                        languages like Pascal or C.  The maximum tab
  290.                        setting allowed is 10.
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.                                                                          Page 5        111483105         Rascal Utilities User's Manual
  302.  
  303.  
  304.                  /wn   sets the width of a page to n characters/line.
  305.                        Use this option for printing in compressed format,
  306.                        since the default is 80 characters/line.  Up to
  307.                        132 characters may be used.
  308.  
  309.                        Note:                       _____
  310.  
  311.                        This option is unaffected by the setting of the MS
  312.                        DOS "mode" command.
  313.  
  314.  
  315.             For normal use printing Rascal source files, you shouldn't
  316.         need to use any of these options.  Here are some examples of
  317.         LLIST:
  318.  
  319.                  A>llist a:debug.inc
  320.  
  321.                       prints the file A:DEBUG.INC with standard tabs,
  322.                       page length (60 lines/page), and page width (80
  323.                       characters/line).
  324.  
  325.  
  326.                  A>llist screen.inc /t2 /p
  327.  
  328.                       prints SCREEN.INC from the A: drive with tabs set
  329.                       every 2 columns and a pause after every page.
  330.  
  331.  
  332.                  A>llist b:input.inc /w132 /l82 /p
  333.  
  334.                       prints the file INPUT.INC on drive B: with a page
  335.                       width of 132 characters/line and a page length of
  336.                       82 lines/page. The switch /p is used to that the
  337.                       paper can be manually advanced after every page.
  338.                       This combination of options can be used for
  339.                       extremely compressed listings on an Epson or IBM PC
  340.                       printer.
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.                                                                          Page 6        111483105         Rascal Utilities User's Manual
  362.  
  363.  
  364.  
  365.         SAMPLE LIBRARY FILES        SAMPLE LIBRARY FILES
  366.  
  367.             The files SCREEN.INC and INPUT.INC on the Rascal program disk
  368.         contain several useful procedures for handling screen input and
  369.         output.
  370.  
  371.             SCREEN.INC contains routines for drawing boxes and frames on
  372.         the screen, putting status messages on line 24, and drawing
  373.         titles and headings.
  374.  
  375.             INPUT.INC contains routines for getting strings with INKEY$,
  376.         reading a single character from the keyboard, and simulating a
  377.         blinking cursor under program control.
  378.  
  379.             These library files can be included in your programs with the
  380.         statements:
  381.  
  382.                  INCLUDE SCREEN.INC
  383.  
  384.         and
  385.  
  386.                  INCLUDE INPUT.INC
  387.  
  388.             Descriptions of the routines can be found in the files
  389.         themselves.  Studying them is also a good way to learn more about
  390.         using Rascal.  The sample Rascal programs CHARS.RAS, ATTRIB.RAS
  391.         and SDIR.RAS all make use of these procedures.
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.                                                                          Page 7        111483105